---
title: Hooks
description: Reuse React Query Builder's logic in your own components
---

import { DemoLink } from '@site/src/components/DemoLink';

%importmd ../\_ts_admonition.md

These hooks are used internally by React Query Builder and exported for use in custom components.

## State access

React Query Builder uses Redux within a custom React context to manage state without interfering with existing Redux stores.

### `useQueryBuilderQuery`

Retrieves the complete, current query object for the nearest ancestor `QueryBuilder` component.

The optional parameter should only be used when retrieving a query object from a different `QueryBuilder` than the nearest ancestor. It can be either a complete props object as passed to a custom component or any object matching the interface `{ schema: { qbId: string } }`.

```ts
function useQueryBuilderQuery(props?: { schema: { qbId: string } }): RuleGroupTypeAny;
```

:::tip

As a React hook, this function must follow the [appropriate rules](https://react.dev/warnings/invalid-hook-call-warning). It provides access to the current query during the render phase, _not in event handlers_.

**To access the current query from an event handler, use `props.schema.getQuery()` instead.**

:::

### `useQueryBuilderSelector`

:::tip

Prefer [`useQueryBuilderQuery`](#usequerybuilderquery) if you only need the query object for the nearest ancestor `QueryBuilder` component.

:::

Returns the current query from the Redux store when used with `getQuerySelectorById` (see example below).

```ts
function useQueryBuilderSelector(selector: (state: RqbState) => RuleGroupTypeAny): RuleGroupTypeAny;
```

Example:

```ts
const CustomValueEditor = (props: ValueEditorProps) => {
  const fullQuery = useQueryBuilderSelector(getQuerySelectorById(props.schema.qbId));
  // Here you can use utilities like `findPath(getParentPath(props.path), fullQuery)`.
  // This allows you to, for example, inspect the parent group of the current rule.
  // You can then count sibling rules, check for unique `field` selections, etc.
  // That information can be used for validation, information to the user, or
  // anything else in your render function.
};
```

## Component logic

The core logic of each component is encapsulated in a reusable hook. Each main component is little more than a call to its respective hook plus the JSX that uses the properties returned from that hook. This enables creating a custom presentation layer without copying logic code from the default components.

:::tip

The `@react-querybuilder/native` package demonstrates this concept well. It calls the hooks from its own query builder, rule group, and rule components, but nests the sub-components within React Native `View` elements instead of HTML `div` elements used by `react-querybuilder` components.

:::

### `useRule`

Called by the [`Rule`](../components/rule) component. See [source code](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/react-querybuilder/src/hooks/useRule.ts) for returned properties.

```ts
function useRule(props: RuleProps): {
  // See source code for returned properties
};
```

### `useRuleGroup`

Called by the [`RuleGroup`](../components/rulegroup) component. See [source code](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/react-querybuilder/src/hooks/useRuleGroup.ts) for returned properties.

```ts
function useRuleGroup(props: RuleGroupProps): {
  // See source code for returned properties
};
```

### `useValueEditor`

Called by the [`ValueEditor`](../components/valueeditor) component. Accepts the same `ValueEditorProps` as the component and returns an object with these properties: the value as an array, a multi-value handler, a processed version of the `parseNumbers` prop, and the classname(s) to be applied to each editor in editor series.

```ts
function useValueEditor(props: ValueEditorProps): {
  valueAsArray: any[];
  multiValueHandler: (val: string, idx: number) => void;
  parseNumberMethod: ParseNumberMethod;
  valueListItemClassName: string;
};
```

This hook updates the `value` as a side effect when these conditions are true:

- `skipHook` is `false` (the value editors in the [compatibility packages](../compat) set this to `true` to avoid infinite loops)
- `inputType` is `"number"`
- `operator` is something other than `"between"`, `"notBetween"`, `"in"`, or `"notIn"`
- `valueEditorType` is not "multiselect"
- `value` is an array or a string containing a comma (`,`) and at least one non-whitespace character on either side.

If all of these conditions are met, `handleOnChange` will be called with the first element of the array, or any characters before the first comma if `value` is a string.

### `useValueSelector`

Called by the [`ValueSelector`](../components/valueselector) component. Returns the given value as an array (unchanged if already an array) and a memoized change handler.

```ts
function useValueSelector(
  props: Pick<ValueSelectorProps, 'handleOnChange' | 'listsAsArrays' | 'multiple' | 'value'>
): {
  onChange: (v: string | string[]) => void;
  val?: string | any[];
};
```

### `useSelectElementChangeHandler`

Used by the [`ValueSelector`](../components/valueselector) component. Returns a memoized change handler designed specifically for HTML `<select />` elements.

```ts
function useSelectElementChangeHandler(props: {
  multiple?: boolean;
  onChange: (v: string | string[]) => void;
}): (e: ChangeEvent<HTMLSelectElement>) => void;
```

### `useShiftActions`

Used by the [`ShiftActions`](../components/shiftactions) component. Generates `shiftUp` and `shiftDown` methods to move a rule/group up or down in the query hierarchy, plus `shiftUpDisabled`/`shiftDownDisabled` to indicate whether either button should be disabled (`shiftUpDisabled` is `true` for the first rule/group in the root group; `shiftDownDisabled` is `true` for the last rule/group in the root group).

```ts
function useShiftActions(
  props: { path: Path } & Pick<Schema, 'combinators' | 'dispatchQuery' | 'getQuery'>
): {
  shiftDown: () => void;
  shiftDownDisabled: boolean;
  shiftUp: () => void;
  shiftUpDisabled: boolean;
};
```

### `useStopEventPropagation`

Used by the default [`Rule`](../components/rule) and [`RuleGroup`](../components/rulegroup) components to prevent default behavior and stop event propagation (e.g., a `MouseEvent` after clicking a `<button>`). Takes a function that accepts a `MouseEvent` and context parameters, then returns a new function that calls `event.preventDefault()` and `event.stopPropagation()` before calling the original function with the same arguments.

```ts
function useStopEventPropagation(
  method: (event: React.MouseEvent, context: any) => void
): (event: React.MouseEvent, context: any) => void;
```

This hook is _not_ used in `RuleNative` and `RuleGroupNative`—the `Rule` and `RuleGroup` components for `@react-querybuilder/native`.

### `useQueryBuilder`

Returns everything needed to render a [`QueryBuilder`](../components/querybuilder) component. Internally, this hook passes the result of [`useQueryBuilderSetup`](#usequerybuildersetup) to [`useQueryBuilderSchema`](#usequerybuilderschema) and returns the result of `useQueryBuilderSchema`. The returned object combines the results of `useQueryBuilderSchema` and `useQueryBuilderSetup` (see below).

As with `useQueryBuilderSchema`, this Hook must be called from a descendant component of `QueryBuilderStateProvider`. See [`QueryBuilder` source code](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/react-querybuilder/src/components/QueryBuilder.tsx) for an example.

:::info

This hook is unlikely to be necessary unless you're reimplementing the _entire_ `QueryBuilder` component structure.

:::

### `useQueryBuilderSetup`

Called by the internal component rendered by [`QueryBuilder`](../components/querybuilder). Merges props and context values with the defaults and generates actions.

:::info

This hook is unlikely to be necessary unless you're reimplementing the _entire_ `QueryBuilder` component structure.

:::

```ts
function useQueryBuilderSetup(props: QueryBuilderProps): {
  qbId: qbId.current;
  rqbContext: ReturnType<typeof useMergedContext>;
  fields: OptionList<Field>;
  fieldMap: Record<string, Field>;
  combinators: OptionList<Combinator>;
  getOperatorsMain: (field: string) => OptionList<Operator>;
  getRuleDefaultOperator: (field: string) => string;
  getValueEditorTypeMain: (field: string, operator: string) => ValueEditorType;
  getValueSourcesMain: (field: string, operator: string) => ValueSources;
  getValuesMain: (field: string, operator: string) => OptionList;
  getRuleDefaultValue: (rule: RuleType) => any;
  getInputTypeMain: (field: string, operator: string) => string;
  createRule: () => RuleType;
  createRuleGroup: () => RuleGroupTypeAny;
};
```

### `useQueryBuilderSchema`

Called by the internal component rendered by [`QueryBuilder`](../components/querybuilder). Returns everything needed to render a wrapper element (e.g., `<div>`) and the root [`RuleGroup`](../components/rulegroup) element based on the provided props and the result from [`useQueryBuilderSetup`](#usequerybuildersetup).

This Hook must be called from a descendant component of `QueryBuilderStateProvider`. See [`QueryBuilder` source code](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/react-querybuilder/src/components/QueryBuilder.tsx) for an example.

:::info

This hook is unlikely to be necessary unless you're reimplementing the _entire_ `QueryBuilder` component structure.

:::

```ts
function useQueryBuilderSchema(
  props: QueryBuilderProps,
  setup: ReturnType<typeof useQueryBuilderSetup>
): QueryBuilderProps & {
  actions: QueryActions;
  rootGroup: RuleGroupTypeAny;
  rootGroupDisabled: RuleGroupTypeAny;
  queryDisabled: boolean;
  rqbContext: ReturnType<typeof useMergedContext>;
  schema: Schema;
  translations: TranslationsFull;
  wrapperClassName: string;
  dndEnabledAttr: 'enabled' | 'disabled';
  inlineCombinatorsAttr: 'enabled' | 'disabled';
  combinatorPropObject: Pick<RuleGroupProps, 'combinator'>;
};
```

## Other utilities

### `useAsyncOptionList`

Augments a `ValueSelectorProps` or `ValueEditorProps` object with [async option loading](../tips/async-option-lists).

```tsx
import { type UseAsyncOptionListParams, useAsyncOptionList } from 'react-querybuilder';

const useAsyncOptionListParams: UseAsyncOptionListParams = {
  getCacheKey: 'field',
  loadOptionList: async (value, { ruleOrGroup }) => {
    const response = await fetch(`/api/operators?field=${ruleOrGroup.field}`);
    return response.json();
  },
};

const AsyncOperatorSelector = (props: ValueSelectorProps) => {
  const asyncProps = useAsyncOptionList(props, useAsyncOptionListParams);

  return <props.schema.controls.valueSelector {...asyncProps} />;
};

const App = () => <QueryBuilder controlElements={{ operatorSelector: AsyncOperatorSelector }} />;
```

### `useMergedContext`

Merges the values inherited from the nearest ancestor `QueryBuilderContext.Provider` with the current component's props. For `controlClassnames`, `controlElements`, and `translations`, options that are not defined through either context or props will fall back to the defaults.

```ts
function useMergedContext(props: QueryBuilderContextProps): QueryBuilderContextProps;
```

### `usePreferProp`

Given a default value, a prop value, and a context value (all `boolean` or `undefined`), returns the first one that is not `undefined` in the order of (1) prop, (2) context, (3) default.

```ts
function usePreferProp(default: boolean, prop?: boolean, context?: boolean): boolean;
```

### `usePrevious`

Returns the value of a prop or state variable from the previous render.

```ts
function usePrevious<T>(prop: T): T | null;
```

## Internal

These hooks log error messages to the console in certain situations (only in "development" mode). They encourage correct usage of React Query Builder and aren't intended for use in custom components.

### `useControlledOrUncontrolled`

Logs an error to the console if any of the following are true:

- Both `query` and `defaultQuery` props are defined.
- The `query` prop is defined during one render and undefined in a subsequent render.
- The `query` prop is undefined during one render and defined in a subsequent render.

### `useDeprecatedProps`

Logs an error to the console if any of the following are true:

- `QueryBuilder` is rendered with `independentCombinators` prop (see [Independent combinators](../components/querybuilder#independent-combinators))
- `RuleGroup` is rendered with `combinator` or `rules` props (deprecated in favor of `ruleGroup`)
- `Rule` is rendered with `field`, `operator`, or `value` props (deprecated in favor of `rule`)

### `useReactDndWarning`

Logs an error to the console if the `enableDragAndDrop` prop is `true` but the `react-dnd` and `react-dnd-html5-backend` dependencies are not loaded.
